…mplementation

- Preserve the original monolithic implementation in `_client_legacy.py` and `_usage_manager_legacy.py`.
- Update `RequestExecutor` to support transaction logging, request sanitization, and consecutive quota failure detection.
- Implement `ConcurrentLimitChecker` in the usage limit engine to enforce `max_concurrent` constraints.
- Improve `StreamingHandler` with robust error buffering for fragmented JSON responses.
- Add fair cycle reset logic and quota baseline synchronization to the new `UsageManager`.

This overhaul introduces smart queuing for credential acquisition and shared quota tracking.

- Implement async waiting in `UsageManager`: calls to `acquire_credential` now block (up to a deadline) using asyncio primitives when keys are busy or on cooldown.
- Add Quota Group synchronization: request counts are now synced across models that share a specific quota pool (e.g., Antigravity variants).
- Add support for cached prompt token tracking in usage statistics.
- Refactor `RequestExecutor` to reuse a shared `httpx.AsyncClient` for better performance.
- Correct token counting for Antigravity models by including preprompt overhead.

BREAKING CHANGE: `UsageManager.acquire_credential` is now `async` and must be awaited. `RequestExecutor` now requires an `http_client` argument during initialization.

- **error_handler**: Implement logic to extract `quotaValue` and `quotaId` from Google/Gemini error responses for better rate limit observability.
- **streaming**: Remove legacy `UsageManager` support and the `__init__` method from `StreamingHandler`; usage recording is now delegated to `CredentialContext`.
- **client**: Handle `_parent_log_dir` internal parameter to configure transaction logger output directory.

This commit introduces a comprehensive overhaul of the usage tracking system to support more complex quota management scenarios and integration capabilities.

- **Granular Usage Scopes**: Usage windows can now be scoped to specific models, quota groups, or credentials via `WindowDefinition.applies_to`, enabling precise limit enforcement (e.g., shared model quotas vs. individual key limits).
- **Cost Calculation**: Integrated `litellm` cost calculation for both standard and streaming requests. `approx_cost` is now tracked and persisted in usage statistics.
- **Provider Hooks**: Added `HookDispatcher` and `on_request_complete` interface, allowing provider plugins to intercept request results, override usage counts, or trigger exhaustion based on custom logic.
- **Usage API**: Introduced `UsageAPI` facade (`src/rotator_library/usage/integration/api.py`) to provide a stable interface for external components to query state and manage cooldowns.
- **Fair Cycle Enhancements**: Refined fair cycle tracking with support for global state persistence and configurable tracking modes (credential-level vs. group-level).
- **Configuration**: Expanded environment variable support for custom caps, fair cycle settings, and sequential fallback multipliers.
- **Persistence**: Updated storage schema to handle nested `model_usage` and `group_usage` statistics.

Also in this commit:
- feat(client): add automatic request validation via provider plugins
- fix(streaming): correctly track cached vs. uncached tokens in usage stats
- refactor: add backward compatibility shim in `src/rotator_library/usage_manager.py

Refines the request executor and client to support deep observability and dynamic quota management within the modular architecture.

- **Observability**:
  - Implement a sanitized LiteLLM logging callback to safely pipe provider logs to the library logger.
  - Capture response headers in `UsageManager`, `CredentialContext`, and failure logs to aid debugging.
  - Pass request headers to the failure logger for better context.
- **Usage Management**:
  - Implement `_apply_usage_reset_config` to dynamically generate rolling window definitions (e.g., daily limits) based on provider settings.
  - Fix `fair_cycle_key` resolution logic in the tracking engine.
- **Client & Executor**:
  - Support passing provider-specific LiteLLM parameters via `RequestExecutor`.
  - Update `BackgroundRefresher` to support the new usage manager registry and prevent crashes when managers are missing.

…ization

This commit overhauls how usage statistics are aggregated and initialized to support shared quotas and improve stability.

- **Quota Groups**: Implemented `_backfill_group_usage` to derive shared group statistics (e.g., tiered limits) from individual model windows. Updated `CooldownChecker` to enforce limits at both model and group levels.
- **Initialization**: Added `initialize_usage_managers` with async locking to `RotatingClient`. Updated `main.py` and `background_refresher.py` to invoke this explicitly, ensuring state is loaded before traffic.
- **Persistence**: Switched storage mechanisms to `ResilientStateWriter` and `safe_read_json` to prevent data corruption during atomic writes.
- **Providers**: Refined quota calculations (calculating `quota_used` from fractions) for Chutes, Firmware, and NanoGPT.
- **Antigravity**: Updated system prompts to strictly enforce parallel tool calling behavior.
- **Logging**: Implemented batched logging for quota exhaustion events to reduce noise.

…t execution

This commit introduces comprehensive usage tracking and refactors the client execution flow for better observability and stability.

- Refactor `RotatingClient.acompletion` to be explicitly `async`, ensuring proper execution in `proxy_app`.
- Implement detailed usage summaries in `get_usage_stats`, including token caching percentages, approximate costs, and detailed provider states.
- Add granular logging in `RequestExecutor` to trace credential availability (displaying blocks by cooldowns, fair cycle, or caps) and current quota window saturation.
- Introduce debounced state saving in `UsageManager` to optimize storage I/O and add logic for backfilling model usage data.

BREAKING CHANGE: `RotatingClient.acompletion` is now an `async` function and must be awaited by the caller.

…window manager

- Update `RequestExecutor` to await `usage_manager.get_availability_stats`, ensuring non-blocking execution during availability checks.
- Expose `window_manager` directly as a property on `UsageManager`.
- Refactor `RequestExecutor` to access `window_manager` directly instead of traversing via `limits.windows`.

Expanded the usage tracking system to capture and persist detailed token metrics, specifically reasoning (thinking) tokens and cache creation tokens.

- Updated client executors to extract `reasoning_tokens` and `cache_creation_tokens` from provider responses.
- Extended `UsageStats` and `WindowStats` models to store granular token breakdowns and explicit success/failure counts.
- Adapted storage and aggregation logic to persist and calculate these new metrics across quota windows.

…tions

- Archive the existing `RotatingClient` and `UsageManager` logic into new `_legacy` modules (`_client_legacy.py` and `_usage_manager_legacy.py`). This preserves the stable baseline implementation to facilitate reference and comparison during the ongoing core architecture refactor.
- Add `src/rotator_library/providers/example_provider.py` as a comprehensive reference template. This file documents the standard patterns for implementing providers with advanced usage management, quota groups, custom token counting, and background refresh jobs.

…ntation

This introduces a thread-safe mechanism using `contextvars` to accurately track and report internal API retries within providers.

- Implement `ContextVar` retry counting in `AntigravityProvider` to capture hidden API costs from internal retries (e.g., on empty responses or malformed calls).
- Update `ExampleProvider` with comprehensive patterns for custom usage handling, including retry counting and error-based cooldowns.
- Expand documentation for `UsageAPI` and `HookDispatcher` with detailed usage examples and architectural context.

Updates the usage manager to prevent lower (stale) API usage values from overwriting higher (current) local counters during background synchronizations. API providers often return cached data or update in increments, causing local state regression.

- Implement `max(local, api)` logic for request counts to ensure monotonic growth
- Add `force` parameter to `UsageManager` and quota trackers to allow manual overrides
- Preserve accurate local tracking while allowing forced resets

This introduces a compatibility layer that allows the `RotatingClient` to accept Anthropic-format requests, translating them to the internal OpenAI format for processing and converting responses back.

- Implement `AnthropicHandler` with support for `messages` and `count_tokens`.
- Integrate handler into `RotatingClient` to enable direct Anthropic SDK usage.

Also in this commit:
- feat(usage): add `force_refresh_quota` and `reload_usage_from_disk` for manual state management
- refactor(usage): implement `reload_from_disk` to sync local state without external calls

This commit extracts the initialization, credential filtering, and validation steps into a reusable `_prepare_execution` helper method within `RequestExecutor`. This ensures consistency and reduces code duplication between streaming and non-streaming request handlers.

Also in this commit:
- refactor(usage): remove unused `release` method from `TrackingEngine

- Add `window_limits_enabled` configuration (default `False`) to allow disabling local window quota blocking.
- Update `LimitEngine` to only include `WindowLimitChecker` when explicitly enabled in config.
- Restore legacy-style logging for quota exhaustion events, including reset time calculations.
- Re-implement fair cycle exhaustion logging to track credential usage status.
- Modify window exhaustion logic to only apply cooldowns when forced.

- Update `UsageManager` logic to apply quota updates to model windows only when no `group_key` is provided.
- Ensure usage is attributed to the correct scope (group vs. model), preventing model window updates when API-level group quotas are active where specific model attribution may be unknown or irrelevant.

…imestamps

- Standardize default configuration by replacing the specific `daily` window with a generic 24h `rolling` window.
- Remove the deprecated `total` window definition and add logic to ignore legacy "total" windows during storage parsing.
- Add `*_human` date string fields (e.g., `reset_at_human`, `last_updated_human`) alongside Unix timestamps in storage dumps to improve debugging and observability.

The quota display logic in `RequestExecutor` now implements a fallback strategy. It prioritizes shared group limits but falls back to model-specific limits if no group window is found or if the group window lacks a limit.

Changes to defaults:
- Remove `WindowDefinition.total` and the default infinite tracking window.
- Simplify default window configuration to a single primary daily window (removed 5h window).

Also in this commit:
- chore: update `.gitignore` to anchor paths and exclude `oauth_creds/` and `usage/` directories

The tracking engine now checks `self._config.window_limits_enabled` before evaluating window exhaustion for groups and models. This ensures that usage tracking does not mark resources as exhausted based on window limits when the feature is explicitly disabled.

This change introduces a `SingletonABCMeta` metaclass to ensure that all `ProviderInterface` implementations behave as singletons. This resolves state fragmentation issues where different components (UsageManager, Hooks, etc.) held separate instances with distinct caches.

- Implement `SingletonABCMeta` and apply to `ProviderInterface`.
- Remove redundant local instance caching in `HookDispatcher` as class instantiation now guarantees a singleton return.
- Add debug logging in `CredentialFilter` to trace instance creation vs. cache hits.

This commit overhauls how quota exhaustion is determined by delegating the decision to individual providers rather than relying on a generic check in the usage manager.

- Introduce `is_initial_fetch` flag to distinguish between startup synchronization and background refreshes.
- Update `AntigravityQuotaTracker` to only apply API-based exhaustion during initial fetch (due to coarse 20% API update increments), relying on local tracking for subsequent updates.
- Update `BaseQuotaTracker` to strictly validate `reset_timestamp`, ignoring it if the quota is full (1.0 remaining), and applying exhaustion immediately if remaining is 0.
- Refactor `UsageManager` to accept an explicit `apply_exhaustion` boolean from providers.
- Add idempotency check to `TrackingEngine` to prevent duplicate logging of exhaustion events.

…ion parsing

- Introduce `quota_threshold` in Fair Cycle configuration to control exhaustion based on window limit multipliers.
- Implement robust duration string parsing (e.g., "1d2h30m") and flexible cooldown modes (offsets, percentages) for Custom Caps.
- Update `FairCycleChecker` to utilize `WindowManager` for dynamic quota resolution.
- Allow Custom Caps to define limits independent of window clamps and improve cooldown calculation logic.
- Remove redundant explicit exhaustion marking in `TrackingEngine` in favor of centralized checker logic.

The custom cap logic has been overhauled to independently verify both model-level and group-level limits. Previously, the system resolved a single "most specific" cap, which could allow requests to bypass group limits if a model-specific cap was present (or vice versa).

- Implemented `_find_all_caps` to retrieve both priority/default model caps and group caps simultaneously.
- Updated `check` method to validate every applicable cap against its respective usage scope (model stats vs. group stats).
- Extracted validation logic into `_check_single_cap` for better readability and reuse.
- Added `get_all_caps_for` to expose all active limits for a given context.

- Defer initialization of window timers (`started_at`, `reset_at`) until the first request is actually recorded.
- Prevent the display of misleading reset times for windows that have not yet been utilized.
- Update quota synchronization logic to only apply remote reset times and timestamps when usage is detected.

- Change sorting criteria in `QuotaViewer` and `UsageManager` to order by total quota limit (lowest first) rather than remaining percentage.
- Implement alphabetical tie-breaking for groups with equal limits.
- Ensure groups without limits are sorted last.
- Provide a more stable view order that reflects capacity constraints rather than transient usage.

This update enhances the usage statistics tracking and visualization to support advanced proxy features.

- **Usage Logic**: Update `UsageManager` to calculate and expose Fair Cycle exhaustion, group-specific cooldowns, and Custom Cap limits.
- **Status Calculation**: Refine credential status logic to identify a "mixed" state when only specific quota groups are exhausted.
- **UI Indicators**: Add visual markers for Fair Cycle (`:scales:`) and Custom Caps (`:bar_chart:`) in the quota summary and detail views.
- **Rendering**: Standardize emoji usage to Rich text markup (e.g., `:warning:` instead of unicode) across `LauncherTUI` and `QuotaViewer` to ensure consistent alignment and width calculations.

Standardize emoji usage by converting raw unicode characters to `rich` console markup aliases throughout the application. This ensures consistent rendering across different terminal environments and prevents potential encoding issues.

Also in this commit:
- style(ui): adjust column widths in quota viewer for better text alignment

- Remove deprecated `_client_legacy.py` and `_usage_manager_legacy.py` files.
- Refactor `RequestExecutor` to use a `_get_quota_display` helper method, reducing code duplication in logging logic.
- Remove duplicate constant definition in `defaults.py`.
- Fix duplicate export in `usage` module.

…masking

Refactors the library to improve code reusability and maintainability:

- Extract `_log_acquiring_credential` and `_prepare_request_kwargs` methods in `RequestExecutor` to simplify the main `execute` loop.
- Update `mask_credential` in `error_handler` to support a "full" masking style (first 4 + last 4 characters).
- Remove redundant `_mask_accessor` method from `UsageManager` and replace usage with the centralized `mask_credential` utility.